claude code agent teams

claude code agent team 공식문서
Cluade code에서 agent team이 출시됐다. 여러 Claude Code 인스턴스를 팀으로 묶어 병렬 탐색·협업·작업조율을 가능하게하는 기능이다. Swarm이라는 내부적으로 사용하다는 기능이 있었는데 agent team 이라는 이름으로 출시한 것 같다.

참고로 openai 에서 Swarm 이라는 프로젝트가 있었는데 중점적으로 개발하는 것 같지는 않다. 현재는 다른 프로젝트에 편입됨.

최근에 비슷한 아이디어를 만들어보려고 했는데 마침 Claude에서 발표해서 놀랐다.

Subagents와의 차이

	Subagents	에이전트 팀
컨텍스트	자신의 컨텍스트 윈도우; 결과는 호출자에게 반환됨	자신의 컨텍스트 윈도우; 완전히 독립적
통신	메인 에이전트에게만 결과 보고	팀원들이 서로 직접 메시지 전송
조율	메인 에이전트가 모든 작업 관리	자체 조율을 통한 공유 작업 목록
최적 용도	결과만 중요한 집중된 작업	논의 및 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 메인 컨텍스트로 요약됨	높음: 각 팀원이 별도의 Claude 인스턴스

병렬 탐색이 가치 있는 작업에서 효과적이다: 연구/검토, 경쟁 가설 디버깅, 교차 계층 변경(프론트·백·테스트), 신규 모듈 설계 등
단일 세션 대비 조율 오버헤드와 토큰 비용이 크게 증가한다. 일상적 작업은 단일 세션이 더 효율적이다.

활성화 방법

Agent Teams는 기본적으로 비활성화되어 있기 때문에 사용하기 위해서는 활성화를 해줘야한다.

settings.json 사용

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

셸 환경 변수 사용

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

사용 흐름

팀 생성 요청: Claude에게 팀 구조와 역할을 자연어로 설명
표시 모드 선택: 기본은 auto; in-process 또는 분할 창 모드
작업 분배/청구: 공유 작업 목록에서 작업을 할당하거나 팀원이 자체 청구
종료/정리: 팀원을 종료한 뒤 리더에게 팀 정리를 요청

표시 모드

In-process: 한 터미널 안에서 팀원이 실행됨. Shift+Up/Down으로 팀원을 선택해 메시지 전송
분할 창: tmux 또는 iTerm2가 필요하며 각 팀원이 별도 창에 표시됨

팀원 권한과 컨텍스트

팀원은 리더의 권한 모드로 시작
팀원은 독립 컨텍스트 윈도우를 가지며, 생성 시 프로젝트 컨텍스트와 리더의 생성 프롬프트를 받음. 리더의 대화 기록은 전달되지 않음
메시징은 message(개별), broadcast(전체)를 사용. broadcast는 팀 크기에 따라 비용이 증가할 수 있음

예시 시나리오

병렬 코드 리뷰: 보안/성능/테스트 관점으로 팀원을 분리해 같은 PR을 동시 검토
경쟁 가설 조사: 서로 다른 가설을 가진 팀원들이 상호 반박·검증하며 원인에 수렴

제한 사항 (실험적 기능)

in-process 팀원 세션 재개 없음: /resume나 /rewind로 팀원 복구 불가
작업 상태 지연 가능, 수동 업데이트가 필요할 수 있음
종료가 느릴 수 있음: 요청·도구 호출 종료 후 종료됨
세션당 하나의 팀, 중첩 팀 불가, 리더 고정
팀원 권한은 생성 시 리더 모드로 고정
분할 창은 tmux 또는 iTerm2 필요, 일부 터미널은 지원되지 않음

사용기

claude code에 간단한 todo 웹앱을 에이전트 팀으로 병렬로 만들어 달라고 요청해봤다.

알아서 팀을 구성하고 작업을 진행한다. in-process 표시모드로 하면 위와 같이 각각의 에이전트가 하나의 창의 표시된다.

작업 진행 승인 요청시 각각의 에이전트 이름이 표시되는 모습

참고

Claude Code Docs: Claude Code 세션 팀 조율하기